Turnbull China Bikeride/Turnbull China Bikeride - Disc 1.iso/ARGONET/PD/MODULES/CSDVAR.ZIP/ReadMe

Text File | 1997-10-25 | 9KB | 225 lines

CSDVar Module, V2.13 © Musus Umbra, 1996/7
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Do you sometimes wish that Risc OS had the 'Prompt $P' functionality of
DOS?  Do you find it tricky remembering where you are in a directory
tree when using the command line?  Ever wanted the unix 'pwd' command?

Then CSDVar is for you!

**NEW**
CSDVar now also implements a 'directory stack' with pushdir & popdir commands
(amongst others).

**NEW**
CSDVar provides AddToPath and PrependToPath for more sensible setting of
path variables (ie. it ensures that the added directory doesn't exist in
the path already, etc.)


What is it?
~~~~~~~~~~~
CSDVar is a (tiny) module that provides the following functions:
    (1) A *command, 'pwd' that prints out the full pathname
        of the current directory.
    (2) A SWI, CSDVar_Read (&CD0C0) that reads the full
        pathname of the CSD and returns a pointer to it.
    (3) A system variable, CSD$Var that whenever inspected
        will hold the pathname of the CSD.

    *** From here on is new to 2.01 ***

    (4) Long pathnames can be 'clipped' to a reasonable length, with
        some suitable 'elipsis' string inserted in the middle.
        (this only affects the CSD$Var variable, the SWI and *pwd
        still give the full pathname)
    (5) A SWI CSDVar_MaxLen (&CD0C1) that can be used to read/set the
        'clipping' length and/or the 'elipsis' string
    (6) The CSD$Var variable can now be written to (with much the
        same effect as using the MaxLen SWI)
    (7) The 'clipping' function is available via the SWI
        CSDVar_Clip (&CD0C2), (see the source)
    (8) Reasonable *Help text (compacted with the OS dictionary)
    (9) Larger buffer for CSD pathname (440 bytes!)
    (A) Documentation that -gasp- makes sense!

    *** From here on is new to 2.13 ***

    (B) Bug fix in invalid SWI code (damn that PRM)
    (C) New code variable 'PWD$Var' (like CSD$Var but without any
        clipping).
    (D) Modifications to AddToPath so that when adding to an empty
        path a leading ',' inserted.  The old code would omit the comma
        (and so set the path rather than adding to it).  Eg. if foo$path
        is empty, "AddToPath Foo$Path Frob" will now result in foo$path
        becoming ",Frob." rather than "Frob."
    (E) Lots more SWIs (mostly for internal use so undocumented.  Look
        at the source if you're interested).
    (F) Documentation that's -gasp- up to date!


How to use it
~~~~~~~~~~~~~
Probably the best and simplest use is to load the module in your boot
sequence, and then issue a
    *SetMacro CLI$Prompt <CSD$Var> *
command.  Now, whenever you'd normally be presented with a '*' prompt on the
command line, you'll instead have the full pathname of the CSD displayed, and
then the *.

I find this incredibly useful, since I'm always using taskwindows, or ducking
out of the desktop (F12) to do some command line stuff, and I often need to
keep track of where I am in the directory tree.


But I already have something that does that!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
So did I, but the utility I was using had (at least) one fundamental problem:
if the CSD's pathname couldn't be read (due to an error), it caused an endless
string of error messages, often necessitating a reboot.  CSDVar doesn't do
that. If there's an error reading the CSD pathname, then CSDVar will tell you
what the error was in place of the CSD's pathname.  Try it on ADFS::0
without a disc in the drive and you'll see what I mean.  The utility I was
using would have spewed continuous 'Drive empty' messages at me until I'd
appeased it by putting a disc in the drive.  CSDVar will just say 'Drive empty'
once and be done with it.  Much better.


What was all that about 'clipping' and 'elipsis' then?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is new to V2.01.

If you're like me, you like your discs to have a meticulously organised
directory tree, and the thought of a directory with more than about ten
files in it brings you out in the screaming heeby-geebies (can you say
'Anal Retentive', Mr. Freud?), then you'll doubtless have very deep
directory trees.  In these circumstances, having the CSD in the CLI
prompt is *very* useful, but it does get a bit annoying when the CSD's
pathname runs to 70 characters or more...

So, 'clipping'.  Basically, you can tell CSDVar to ensure that the CSD$Var
variable (NB: *not* the output of the *pwd command, or CSDVar_Read swi!)
is never longer than a certain length.  Now, we don't want to chop off the
start of the path - that contains useful things like the disc name, and we
can't chop off the end - that contains the directory name.  So, we chop out
the middle, and replace it with an 'elipsis' string (elipsis is the
symbol '…', sometimes written ... that means 'something missed out here').
You can even specify the elipsis string! (The default is " … ").

You control the maximum length and elipsis string by *set-ing the CSD$Var
variable:

    *set CSD$Var <max length> [<elipsis string>]

Note that you *must* supply the maximum length parameter - if you don't
want to alter the maximum length currently in force, give the new max length
as 0.

If you want to include spaces in the elipsis string (eg. to set it to
the less claustrophobic " ... "), then you should surround the string with
double-quotation marks ("s).

The backslash (\) character means "use the next character 'as is', don't try
anything fancy with it, schmuck!".  So, you could do that last example with
    *set CSD$Var 0 \ ...\        (NB: there's a space after that last \)
but you'd be daft to.  Use \" to include a ", \\ for a \.

Watch out! if you want to use the < character, you have to prefix it with
a pipe (|) character - this isn't my fault! eg:
    *set CSD$Var 0 <chomp>
doesn't set the elipsis string to "<chomp>", it sets it to the contents of
the system variable 'chomp' - this is because RISC OS GSTrans's the command
line *before* CSDVar gets a look at it.
    *set CSD$Var 0 |<chomp>
does the trick though.

If you want to 'unset' the elipsis string (ie. set it to ""), then simply
set it to "":
    *set CSD$Var 0 ""
(note that you have to supply the "", if you don't then CSDVar will simply
think that you've omitted the elipsis string because you didn't want to
alter it).



*Commands
~~~~~~~~~
The module provides plenty of *Help text :-)



Technical Stuff & SWI calls
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The CSDVar SWI chunk is &CD0C0 (unregistered)

The SWIs are (all regs not documented are preserved)

SWI CSDVar_Read (&CD0C0)
    On Entry:    -
    On Exit:    r0->the full pathname of the CSD (or error string)
    Description:
        This swi is used internally (the code variable can't
        get at the module's workspace directly, so it does all
        its 'dirty' work via swi calls).

SWI CSDVar_MaxLen (&CD0C1)
    On Entry:    r0 = new max length of CSD$Var, or 0 to leave alone
            r1 = new elipsis string, or 0 to leave alone
    On exit:    r0 = max length in effect after the call
            r1 -> elipsis string in effect after the call
    Description:
        Once again, this is a swi that's only there because the
        code variable can't get at the module workspace itself.
        When the code variable is written to, it parses the
        'arguments' and calls this swi. Note that the elipsis
        string isn't processed in any way:
            *set CSD$Var 0 |<chomp>\"Hi\"
        is not the same as:
            SYS "CSDVar_MaxLen",0,"|<chomp>\""Hi\"""
        even though the elipsis string arguments are the same!
        (the *set results in <chomp>"Hi", whereas the swi results
        in |<chomp>\"Hi\").
        Actually, the code variable uses the elipsis pointer
        returned to overwrite the current string, rather than
        passing a new string in.  Yicky, I know, but it saves
        a huge amount of hassle.



Background
~~~~~~~~~~
Basically, I'd been using a similar utility to set the CLI prompt to the
name of the CSD, but I'd got increasingly upset with it.  The principal
problem was that if the CSD couldn't be read for some reason (eg. I'd changed
to IDEFS, but my IDE drive is disconnected now that I have a bigger, faster
SCSI drive) and there was an error, I'd get an endless stream of (for
instance) 'Bad Drive's appearing when I hit F12, and the only option would be
a re-boot.  Now, why the Hell didn't whoever wrote the utility I was using
simply trap the error and use that for the name of the CSD in the system
prompt?  I don't know, but that's exactly what my module does.  Also, my module
will allow you to 'unset' the system variable it provides - not fantastically
useful, but if for some arcane reason you want to, you can.


Disclaimer
~~~~~~~~~~
Use of this software is completely at your own risk. The author can accept no
responsibility for any damage/loss arising from the use, or inability to use
this software. No warranty, express or implied, applies to this software.
This is not PD: the Copyright in this software belongs at all times to the
author. However, permission is granted for unrestricted distribution
prodividing that *no* charge is made for the distribution [a charge may be made
for handling/media] and that the whole of the software is supplied intact and
unaltered. Permission is also granted for unrestricted use and alteration of
the software [but if you fix a bug / add anything nice, let me know so I can
patch the 'master' version].



Bug reports / comments / etc to:

Musus Umbra c/o 23 Baronsway, Whitkirk, Leeds, LS15 7AW, England.

e-mail: [e-mail]
www:    http://www.argonet.co.uk/users/musus/